---
title: Déployer votre site Astro sur GitHub Pages
description: Comment déployer votre site Astro sur le Web à l'aide de GitHub Pages.
sidebar:
  label: GitHub Pages
type: deploy
logo: github
supports: ['static']
i18nReady: true
---
import { Steps } from '@astrojs/starlight/components';

Vous pouvez utiliser [GitHub Pages](https://pages.github.com/) pour héberger un site Astro statique et pré-rendu directement à partir d'un dépôt sur [GitHub.com](https://github.com/) en utilisant [les actions de GitHub](https://github.com/features/actions).

## Comment déployer

Astro maintient une [action GitHub officielle dédiée à Astro pour déployer votre projet sur GitHub Pages](https://github.com/withastro/action) nécessitant très peu de configuration. Il s'agit du moyen privilégié pour déployer sur GitHub Pages.

Suivez les instructions ci-dessous pour utiliser l'action GitHub afin de déployer votre site Astro sur GitHub Pages. Cela créera un site web à partir de votre dépôt, avec une URL GitHub (par exemple, `https://<nom-utilisateur>.github.io/<mon-depot>`). Une fois déployé, vous pouvez éventuellement [configurer un domaine personnalisé](#remplacer-votre-url-github-par-un-domaine-personnalisé) pour déployer votre site GitHub Pages sur votre domaine préféré (par exemple `https://example.com`).

<Steps>
1. Créez un nouveau fichier `.github/workflows/deploy.yml` dans votre projet et collez le YAML ci-dessous.

    ```yaml title="deploy.yml"
    name: Déployer sur GitHub Pages

    on:
      # Déclenchez le workflow à chaque fois que vous poussez vers la branche `main`
      # Vous utilisez un nom de branche différent ? Remplacez `main` par le nom de votre branche.
      push:
        branches: [ main ]
      # Vous permet d'exécuter ce workflow manuellement à partir de l'onglet Actions sur GitHub.
      workflow_dispatch:
      
    # Autoriser cette tâche à cloner le dépôt et à créer un déploiement de page
    permissions:
      contents: read
      pages: write
      id-token: write

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Extraire votre dépôt à l'aide de git
            uses: actions/checkout@v5
          - name: Installer, compiler et télécharger votre site
            uses: withastro/action@v5
            # with:
              # path: . # L'emplacement racine de votre projet Astro dans le dépôt. (facultatif)
              # node-version: 24 # Version spécifique de Node à utiliser pour compiler votre site. La valeur par défaut est 22. (facultatif)
              # package-manager: pnpm@latest # Gestionnaire de paquets Node à utiliser pour installer les dépendances et compiler votre site. Détecté automatiquement en fonction de votre fichier de verrouillage. (facultatif)
              # build-cmd: pnpm run build # La commande à exécuter pour compiler votre site. Exécute par défaut le script/la tâche de compilation du paquet. (facultatif)
            # env:
              # PUBLIC_POKEAPI: 'https://pokeapi.co/api/v2' # Utilisez des guillemets simples pour la valeur de la variable. (facultatif)

      deploy:
        needs: build
        runs-on: ubuntu-latest
        environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
        steps:
          - name: Déployer sur GitHub Pages
            id: deployment
            uses: actions/deploy-pages@v4
    ```

     L'action Astro peut être configurée avec des entrées facultatives. Fournissez-les en décommentant la ligne `with:` et l'entrée que vous souhaitez utiliser.
     
     Si votre site nécessite des variables d'environnement publiques, décommentez la ligne `env:` et ajoutez-les ici. (Consultez la [documentation GitHub sur la définition des secrets](https://docs.github.com/fr/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#creating-configuration-variables-for-a-repository) pour ajouter des variables d'environnement privées.)
    
    :::caution
    L'[action](https://github.com/withastro/action) officielle d'Astro recherche un fichier de verrouillage pour détecter votre gestionnaire de paquets préféré (`npm`, `yarn`, `pnpm` ou `bun`). Vous devez envoyer le fichier `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` ou `bun.lockb` généré automatiquement par votre gestionnaire de paquets dans votre dépôt.
    :::

2. Dans votre fichier de configuration Astro, définissez [`site`](/fr/reference/configuration-reference/#site) avec l'URL GitHub de votre site déployé.

    ```js title="astro.config.mjs" ins={4}
    import { defineConfig } from 'astro/config'

    export default defineConfig({
      site: 'https://astronaut.github.io',
    })
    ```

    La valeur de `site` doit être l’une des suivantes :

    - L'URL suivante reposant sur votre nom d'utilisateur : `https://<username>.github.io`
    - L'URL aléatoire générée automatiquement pour une [page privée d'une organisation GitHub](https://docs.github.com/fr/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site) : `https://<chaine-de-caracteres-aleatoire>.pages.github.io/`

3. Dans `astro.config.mjs`, configurez une valeur pour [`base`](/fr/reference/configuration-reference/#base) (généralement requis).

      GitHub Pages publiera votre site web à une adresse qui dépend à la fois de votre nom d'utilisateur et du nom de votre dépôt (par exemple, `https://<nom-utilisateur>/github.io/<mon-depot>/`). Définissez une valeur pour « base » qui spécifie le dépôt de votre site web. Cela permet à Astro de comprendre que la racine de votre site web est `/mon-depot`, plutôt que la valeur par défaut `/`. Vous pouvez ignorer cette étape si le nom de votre dépôt correspond au modèle spécial `<nom-utilisateur>.github.io` (par exemple, `https://github.com/nom-utilisateur/nom-utilisateur.github.io/`).

      Configurez `base` comme nom du dépôt commençant par une barre oblique (par exemple, `/mon-depot`) :

      ```js title="astro.config.mjs" ins={4-5}
      import { defineConfig } from 'astro/config'
  
      export default defineConfig({
        site: 'https://astronaut.github.io',
        base: '/mon-depot',
      })
      ```

      :::caution[Liens internes quand `base` est configurée]
      Lorsque cette valeur est configurée, tous les liens internes à vos pages doivent être préfixés par la valeur de votre `base` :

      ```astro ins="/mon-depot"
      <a href="/mon-depot/a-propos">À propos</a>
      ```
  
      En savoir plus sur [la configuration d'une valeur pour `base`](/fr/reference/configuration-reference/#base).
      :::

4. Sur GitHub, accédez à l’onglet **Paramètres** de votre dépôt et recherchez la section **Pages** des paramètres.

5. Choisissez **GitHub Actions** comme **Source** de votre site.

</Steps>

Lorsque vous envoyez des modifications dans le dépôt de votre projet Astro, l’action GitHub les déploiera automatiquement pour vous sur votre URL GitHub.

## Remplacer votre URL GitHub par un domaine personnalisé

Une fois votre projet Astro [déployé sur GitHub Pages à une URL GitHub](#comment-déployer) en suivant les instructions précédentes, vous pouvez configurer un domaine personnalisé. Cela signifie que les utilisateurs peuvent visiter votre site via votre domaine personnalisé `https://example.com` au lieu de `https://<nom-utilisateur>.github.io`.

<Steps>

1. [Configurez le DNS pour votre fournisseur de domaine](https://docs.github.com/fr/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain).
2. Ajoutez un enregistrement `./public/CNAME` à votre projet.

    Créez le fichier suivant dans votre dossier `public/` avec une seule ligne de texte qui spécifie votre domaine personnalisé :
    ```js title="public/CNAME"
    sub.example.com
    ```

    Cela déploiera votre site sur votre domaine personnalisé au lieu de `utilisateur.github.io`.

3. Dans votre configuration Astro, remplacez la valeur de `site` par votre domaine personnalisé. Ne définissez pas de valeur pour `base` et supprimez-la si elle existe :

    ```js title="astro.config.mjs" ins={4} del={5}
    import { defineConfig } from 'astro/config'

    export default defineConfig({
      site: 'https://example.com',
      base: '/mon-depot'
    })
    ```

4. Si nécessaire, mettez à jour tous les liens internes à vos pages pour supprimer le préfixe `base` :

    ```astro del="/mon-depot"
    <a href="/mon-depot/a-propos">À propos</a>
    ```

</Steps>

## Exemples

- [Modèle de démarrage pour le déploiement sur Github Pages](https://github.com/hkbertoson/github-pages)
- [Thème Flexoki pour Starlight (site en production)](https://delucis.github.io/starlight-theme-flexoki/)
- [Puces de couleur pour Expressive Code (site en production)](https://delucis.github.io/expressive-code-color-chips/)
- [Blocs Markdown pour Starlight (site en production)](https://delucis.github.io/starlight-markdown-blocks/)
